import { Tabs } from 'nextra/components'
import BadgeGroup, { UniverTypes } from '@/components/BadgeGroup'

# Using Univer Plugins

<BadgeGroup values={[UniverTypes.GENERAL]} value={UniverTypes.GENERAL} />

For those who are new to Univer, the plugin-based design may bring the following confusion:

- How to know if a plugin contains a language pack?
- How to ensure the correct loading order of plugin style files?
- How to know if a plugin contains a language pack?

These questions may not have simple answers, so we provide some build tool plugins that are the best practices to solve the above problems. These plugins will automatically import style files on demand, generate language packs, etc., so you no longer need to worry about these problems.

We provide build tool plugins that support the following build tools, and you can choose the appropriate plugin according to your build tool.

<section className="flex gap-2 mt-6">
  <a href="#vite-plugin">
    <img src="https://img.shields.io/static/v1?style=for-the-badge&message=Vite&color=222222&logo=Vite&logoColor=FFFFFF&label=" alt="Vite" />
  </a>
  <a href="#esbuild-plugin">
    <img src="https://img.shields.io/static/v1?style=for-the-badge&message=esbuild&color=222222&logo=esbuild&logoColor=FFCF00&label=" alt="esbuild" />
  </a>
  <a href="#webpack-plugin">
    <img src="https://img.shields.io/static/v1?style=for-the-badge&message=Webpack&color=222222&logo=Webpack&logoColor=8DD6F9&label=" alt="Webpack" />
  </a>
</section>

## Vite Plugin

### Installation

<Tabs items={['pnpm', 'npm']}>
  <Tabs.Tab label="pnpm">
    ```shell
    pnpm add @univerjs/vite-plugin -D
    ```
  </Tabs.Tab>
  <Tabs.Tab label="npm">
    ```shell
    npm install @univerjs/vite-plugin -D
    ```
  </Tabs.Tab>
</Tabs>

### Usage

Add the plugin to your `vite.config.ts`:

```typescript
import { defineConfig } from 'vite'
import { univerPlugin } from '@univerjs/vite-plugin'

export default defineConfig({
  plugins: [
    univerPlugin()
  ]
})
```

### Features

#### Automatic Import of Required CSS

This feature is enabled by default. You can disable it by passing `css: false` to the plugin options.

```diff
export default defineConfig({
  plugins: [
    univerPlugin({
+      css: false
    })
  ]
})
```

#### Simplified Import of Language Packs

The plugin provides a virtual module `univer:locales`, which simplifies the import of language packs.

```typescript
import { LocaleType } from '@univerjs/core'

import { zhCN, enUS } from 'univer:locales'

new Univer({
  locales: {
    [LocaleType.ZH_CN]: zhCN,
    [LocaleType.EN_US]: enUS
  }
})
```

### TypeScript Support

In order for TypeScript to recognize the `univer:locales` import, you should add a reference to the `src/vite-env.d.ts` file in your project.

```diff
/// <reference types="vite/client" />
+ /// <reference types="@univerjs/vite-plugin/types" />
```

### Options

- `css`: `boolean` - Whether to automatically import required CSS. Default is `true`.

## ESbuild Plugin

### Installation

<Tabs items={['pnpm', 'npm']}>
  <Tabs.Tab label="pnpm">
    ```shell
    pnpm add @univerjs/esbuild-plugin -D
    ```
  </Tabs.Tab>
  <Tabs.Tab label="npm">
    ```shell
    npm install @univerjs/esbuild-plugin -D
    ```
  </Tabs.Tab>
</Tabs>

### Usage

If you are using the `esbuild` API, you can add the plugin to your build configuration:

```typescript
import esbuild from 'esbuild'

esbuild.build({
  plugins: [
    univerPlugin()
  ],
})
```

### Features

#### Automatic Import of Required CSS

This feature is enabled by default. You can disable it by passing `css: false` to the plugin options.

```diff
esbuild.build({
  plugins: [
    univerPlugin({
+     css: false
    })
  ],
})
```

#### Simplified Import of Language Packs

The plugin provides a virtual module `univer:locales`, which simplifies the import of language packs.

```typescript
import { LocaleType } from '@univerjs/core'

import { zhCN, enUS } from 'univer:locales'

new Univer({
  locales: {
    [LocaleType.ZH_CN]: zhCN,
    [LocaleType.EN_US]: enUS
  }
})
```

### TypeScript Support

In order for TypeScript to recognize the `univer:locales` import, you should add a reference to the `tsconfig.json` file in your project.

```diff
{
  "compilerOptions": {
+    "types": ["@univerjs/esbuild-plugin/types"]
  }
}
```

### Options

- `css`: `boolean` - Whether to automatically import required CSS. Default is `true`.

## Webpack Plugin

### Installation

<Tabs items={['pnpm', 'npm']}>
  <Tabs.Tab label="pnpm">
    ```shell
    pnpm add @univerjs/webpack-plugin -D
    ```
  </Tabs.Tab>
  <Tabs.Tab label="npm">
    ```shell
    npm install @univerjs/webpack-plugin -D
    ```
  </Tabs.Tab>
</Tabs>

### Usage

Add the plugin to your `webpack.config.js`:

```typescript
import { UniverPlugin } from '@univerjs/webpack-plugin'

export default {
  plugins: [
+    new UniverPlugin()
  ]
}
```

### Features

#### Automatic Import of Required CSS

This feature is enabled by default. You can disable it by passing `css: false` to the plugin options.

```diff
export default defineConfig({
  plugins: [
    new UniverPlugin({
+      css: false
    })
  ]
})
```

#### Simplified Import of Language Packs

The plugin provides a virtual module `univer:locales`, which simplifies the import of language packs.

```typescript
import { LocaleType } from '@univerjs/core'

import { zhCN, enUS } from 'univer:locales'

new Univer({
  locales: {
    [LocaleType.ZH_CN]: zhCN,
    [LocaleType.EN_US]: enUS
  }
})
```

### TypeScript Support

In order for TypeScript to recognize the `univer:locales` import, you should add a reference to the `src/webpack-env.d.ts` file in your project.

```diff
+ /// <reference types="@univerjs/webpack-plugin/types" />
```

### Options

- `css`: `boolean` - Whether to automatically import required CSS. Default is `true`.
